SGI Developer Toolbox 6.1

home *** CD-ROM | disk | FTP | other *** search

/ SGI Developer Toolbox 6.1 / SGI Developer Toolbox 6.1 - Disc 4.iso / public / GNU / emacs.inst / emacs19.idb / usr / gnu / info / elisp-17.z / elisp-17

Wrap

GNU Info File | 1994-08-02 | 50.4 KB | 1,194 lines

This is Info file elisp, produced by Makeinfo-1.55 from the input file elisp.texi. This version is newer than the second printed edition of the GNU Emacs Lisp Reference Manual. It corresponds to Emacs Version 19.19. Published by the Free Software Foundation 675 Massachusetts Avenue Cambridge, MA 02139 USA Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU Emacs General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU Emacs General Public License" may be included in a translation approved by the Free Software Foundation instead of in the original English. File: elisp, Node: Documentation, Next: Files, Prev: Modes, Up: Top Documentation ************* GNU Emacs Lisp has convenient on-line help facilities, most of which derive their information from the documentation strings associated with functions and variables. This chapter describes how to write good documentation strings for your Lisp programs, as well as how to write programs to access documentation. Note that the documentation strings for Emacs are not the same thing as the Emacs manual. Manuals have their own source files, written in the Texinfo language; documentation strings are specified in the definitions of the functions and variables they apply to. A collection of documentation strings is not sufficient as a manual because a good manual is not organized in that fashion; it is organized in terms of topics of discussion. * Menu: * Documentation Basics:: Good style for doc strings. Where to put them. How Emacs stores them. * Accessing Documentation:: How Lisp programs can access doc strings. * Keys in Documentation:: Substituting current key bindings. * Describing Characters:: Making printable descriptions of non-printing characters and key sequences. * Help Functions:: Subroutines used by Emacs help facilities. File: elisp, Node: Documentation Basics, Next: Accessing Documentation, Prev: Documentation, Up: Documentation Documentation Basics ==================== A documentation string is written using the Lisp syntax for strings, with double-quote characters surrounding the text of the string. This is because it really is a Lisp string object. The string serves as documentation when it is written in the proper place in the definition of a function or variable. In a function definition, the documentation string follows the argument list. In a variable definition, the documentation string follows the initial value of the variable. When you write a documentation string, make the first line a complete sentence (or two complete sentences) since some commands, such as `apropos', print only the first line of a multi-line documentation string. Also, you should not indent the second line of a documentation string, if you have one, because that looks odd when you use `C-h f' (`describe-function') or `C-h v' (`describe-variable'). Documentation strings may contain several special substrings, which stand for key bindings to be looked up in the current keymaps when the documentation is displayed. This allows documentation strings to refer to the keys for related commands and be accurate even when a user rearranges the key bindings. (*Note Accessing Documentation::.) Within the Lisp world, a documentation string is kept with the function or variable that it describes: * The documentation for a function is stored in the function definition itself (*note Lambda Expressions::.). The function `documentation' knows how to extract it. * The documentation for a variable is stored on the variable's property list under the property name `variable-documentation'. The function `documentation-property' knows how to extract it. However, to save space, the documentation for preloaded functions and variables (including primitive functions and autoloaded functions) are stored in the `emacs/etc/DOC-VERSION' file. The `emacs/etc/DOC-VERSION' file can be accessed by both the `documentation' and the `documentation-property' functions, and the process is transparent to the user. In this case, the documentation string is replaced with an integer offset into the `emacs/etc/DOC-VERSION' file. Keeping the documentation strings out of the Emacs core image saves a significant amount of space. *Note Building Emacs::. For information on the uses of documentation strings, see *Note Help: (emacs)Help. The `emacs/etc' directory contains two utilities that you can use to print nice-looking hardcopy for the file `emacs/etc/DOC-VERSION'. These are `sorted-doc.c' and `digest-doc.c'. File: elisp, Node: Accessing Documentation, Next: Keys in Documentation, Prev: Documentation Basics, Up: Documentation Access to Documentation Strings =============================== - Function: documentation-property SYMBOL PROPERTY &optional VERBATIM This function returns the documentation string that is recorded SYMBOL's property list under property PROPERTY. This uses the function `get', but does more than that: it also retrieves the string from the file `emacs/etc/DOC-VERSION' if necessary, and runs `substitute-command-keys' to substitute the actual (current) key bindings. If VERBATIM is non-`nil', that inhibits running `substitute-command-keys'. (The VERBATIM argument exists only as of Emacs 19.) (documentation-property 'command-line-processed 'variable-documentation) => "t once command line has been processed" (symbol-plist 'command-line-processed) => (variable-documentation 188902) - Function: documentation FUNCTION &optional VERBATIM This function returns the documentation string of FUNCTION. This function will access the documentation string if it is stored in the `emacs/etc/DOC-VERSION' file. In addition, `documentation' runs `substitute-command-keys' on the resulting string, so the value contains the actual (current) key bindings. (This is not done if VERBATIM is non-`nil'; the VERBATIM argument exists only as of Emacs 19.) The function `documentation' signals a `void-function' error unless FUNCTION has a function definition. However, FUNCTION does not need to have a documentation string. If there is no documentation string, `documentation' returns `nil'. Here is an example of using the two functions, `documentation' and `documentation-property', to display the documentation strings for several symbols in a `*Help*' buffer. (defun describe-symbols (pattern) "Describe the Emacs Lisp symbols matching PATTERN. All symbols that have PATTERN in their name are described in the `*Help*' buffer." (interactive "sDescribe symbols matching: ") (let ((describe-func (function (lambda (s) ;; Print description of symbol. (if (fboundp s) ; It is a function. (princ (format "%s\t%s\n%s\n\n" s (if (commandp s) (let ((keys (where-is-internal s))) (if keys (concat "Keys: " (mapconcat 'key-description keys " ")) "Keys: none")) "Function") (or (documentation s) "not documented")))) (if (boundp s) ; It is a variable. (princ (format "%s\t%s\n%s\n\n" s (if (user-variable-p s) "Option " "Variable") (or (documentation-property s 'variable-documentation) "not documented"))))))) sym-list) ;; Build a list of symbols that match pattern. (mapatoms (function (lambda (sym) (if (string-match pattern (symbol-name sym)) (setq sym-list (cons sym sym-list)))))) ;; Display the data. (with-output-to-temp-buffer "*Help*" (mapcar describe-func (sort sym-list 'string<)) (print-help-return-message)))) The `describe-symbols' function works like `apropos', but provides more information. (describe-symbols "goal") ---------- Buffer: *Help* ---------- goal-column Option *Semipermanent goal column for vertical motion, as set by C-x C-n, or nil. set-goal-column Command: C-x C-n Set the current horizontal position as a goal for C-n and C-p. Those commands will move to this position in the line moved to rather than trying to keep the same horizontal position. With a non-nil argument, clears out the goal column so that C-n and C-p resume vertical motion. The goal column is stored in the variable `goal-column'. temporary-goal-column Variable Current goal column for vertical motion. It is the column where point was at the start of current run of vertical motion commands. When the `track-eol' feature is doing its job, the value is 9999. ---------- Buffer: *Help* ---------- - Function: Snarf-documentation FILENAME This function is used only during Emacs initialization, just before the runnable Emacs is dumped. It finds the file offsets of the documentation strings stored in the file FILENAME, and records them in the in-core function definitions and variable property lists in place of the actual strings. *Note Building Emacs::. Emacs finds the file FILENAME in the `emacs/etc' directory. When the dumped Emacs is later executed, the same file is found in the directory `data-directory'. Usually FILENAME is `"DOC-VERSION"'. - Variable: data-directory This variable holds the name of the directory in which Emacs finds certain data files that come with Emacs or are built as part of building Emacs. (In older Emacs versions, this directory was the same as `exec-directory'.) File: elisp, Node: Keys in Documentation, Next: Describing Characters, Prev: Accessing Documentation, Up: Documentation Substituting Key Bindings in Documentation ========================================== This function makes it possible for you to write a documentation string that enables a user to display information about the current, actual key bindings. if you call `documentation' with non-`nil' VERBATIM, you might later call this function to do the substitution that you prevented `documentation' from doing. - Function: substitute-command-keys STRING This function returns STRING with certain special substrings replaced by the actual (current) key bindings. This permits the documentation to be displayed with accurate information about key bindings. (The key bindings may be changed by the user between the time Emacs is built and the time that the documentation is asked for.) This table lists the forms of the special substrings and what they are replaced with: `\[COMMAND]' is replaced either by a keystroke sequence that will invoke COMMAND, or by `M-x COMMAND' if COMMAND is not bound to any key sequence. `\{MAPVAR}' is replaced by a summary of the value of MAPVAR, taken as a keymap. (The summary is made by `describe-bindings'.) `\<MAPVAR>' makes this call to `substitute-command-keys' use the value of MAPVAR as the keymap for future `\[COMMAND]' substrings. This special string does not produce any replacement text itself; it only affects the replacements done later. *Please note:* each `\' must be doubled when written in a string in Emacs Lisp. Here are examples of the special substrings: (substitute-command-keys "To abort recursive edit, type: \\[abort-recursive-edit]") => "To abort recursive edit, type: C-]" (substitute-command-keys "The keys that are defined for the minibuffer here are: \\{minibuffer-local-must-match-map}") => "The keys that are defined for the minibuffer here are: ? minibuffer-completion-help SPC minibuffer-complete-word TAB minibuffer-complete LFD minibuffer-complete-and-exit RET minibuffer-complete-and-exit C-g abort-recursive-edit " (substitute-command-keys "To abort a recursive edit from the minibuffer, type\ \\<minibuffer-local-must-match-map>\\[abort-recursive-edit].") => "To abort a recursive edit from the minibuffer, type C-g." File: elisp, Node: Describing Characters, Next: Help Functions, Prev: Keys in Documentation, Up: Documentation Describing Characters for Help Messages ======================================= These functions convert events, key sequences or characters to textual descriptions. These descriptions are useful for including arbitrary text characters or key sequences in messages, because they convert non-printing characters to sequences of printing characters. The description of a printing character is the character itself. - Function: key-description SEQUENCE This function returns a string containing the Emacs standard notation for the input events in SEQUENCE. The argument SEQUENCE may be a string, vector or list. *Note Input Events::, for more information about valid events. See also the examples for `single-key-description', below. - Function: single-key-description EVENT This function returns a string describing EVENT in the standard Emacs notation for keyboard input. A normal printing character is represented by itself, but a control character turns into a string starting with `C-', a meta character turns into a string starting with `M-', and space, linefeed, etc. are transformed to `SPC', `LFD', etc. A function key is represented by its name. An event which is a list is represented by the name of the symbol in the CAR of the list. (single-key-description ?\C-x) => "C-x" (key-description "\C-x \M-y \n \t \r \f123") => "C-x SPC M-y SPC LFD SPC TAB SPC RET SPC C-l 1 2 3" (single-key-description 'C-mouse-1) => "C-mouse-1" - Function: text-char-description CHARACTER This function returns a string describing CHARACTER in the standard Emacs notation for characters that appear in text--like `single-key-description', except that control characters are represented with a leading caret (which is how control characters in Emacs buffers are usually displayed). (text-char-description ?\C-c) => "^C" (text-char-description ?\M-m) => "M-m" (text-char-description ?\C-\M-m) => "M-^M" File: elisp, Node: Help Functions, Prev: Describing Characters, Up: Documentation Help Functions ============== Emacs provides a variety of on-line help functions, all accessible to the user as subcommands of the prefix `C-h'. For more information about them, see *Note Help: (emacs)Help. Here we describe some program-level interfaces to the same information. - Command: apropos REGEXP &optional DO-ALL PREDICATE This function finds all symbols whose names contain a match for the regular expression REGEXP, and returns a list of them. It also displays the symbols in a buffer named `*Help*', each with a one-line description. If DO-ALL is non-`nil', then `apropos' also shows key bindings for the functions that are found. If PREDICATE is non-`nil', it should be a function to be called on each symbol that has matched REGEXP. Only symbols for which PREDICATE returns a non-`nil' value are listed or displayed. In the first of the following examples, `apropos' finds all the symbols with names containing `exec'. In the second example, it finds and returns only those symbols that are also commands. (We don't show the output that results in the `*Help*' buffer.) (apropos "exec") => (Buffer-menu-execute command-execute exec-directory exec-path execute-extended-command execute-kbd-macro executing-kbd-macro executing-macro) (apropos "exec" nil 'commandp) => (Buffer-menu-execute execute-extended-command) The command `C-h a' (`command-apropos') calls `apropos', but specifies a PREDICATE to restrict the output to symbols that are commands. The call to `apropos' looks like this: (apropos string t 'commandp) - Command: super-apropos REGEXP &optional DO-ALL This function differs from `apropos' in that it searches documentation strings as well as symbol names for matches for REGEXP. By default, it searches only the documentation strings, and only those of functions and variables that are included in Emacs when it is dumped. If DO-ALL is non-`nil', it scans the names and documentation strings of all functions and variables. - Command: help-command This command is not a function, but rather a symbol which is equivalent to the keymap called `help-map'. It is defined in `help.el' as follows: (define-key global-map "\C-h" 'help-command) (fset 'help-command help-map) - Variable: help-map The value of this variable is a local keymap for characters following the Help key, `C-h'. - Function: print-help-return-message &optional FUNCTION This function builds a string which is a message explaining how to restore the previous state of the windows after a help command. After building the message, it applies FUNCTION to it if FUNCTION is non-`nil'. Otherwise it calls `message' to display it in the echo area. This function expects to be called inside a `with-output-to-temp-buffer' special form, and expects `standard-output' to have the value bound by that special form. For an example of its use, see the example in the section describing the `documentation' function (*note Accessing Documentation::.). The constructed message will have one of the forms shown below. ---------- Echo Area ---------- Type C-x 1 to remove help window. ---------- Echo Area ---------- ---------- Echo Area ---------- Type C-x 4 b RET to restore old contents of help window. ---------- Echo Area ---------- - Variable: help-char The value of this variable is the character that Emacs recognizes as meaning Help. When Emacs reads this character (which is usually 8, the value of `C-h'), Emacs evaluates `(eval help-form)', and displays the result if it is a string. If `help-form''s value is `nil', this character is read normally. - Variable: help-form The value of this variable is a form to execute when the character `help-char' is read. If the form returns a string, that string is displayed. If `help-form' is `nil', then the help character is not recognized. Entry to the minibuffer binds this variable to the value of `minibuffer-help-form'. - Variable: prefix-help-command This variable holds a command that prints help for a prefix character. The command is run when the user types the help character after a prefix character. The default value of `prefix-help-command' is `describe-prefix-bindings'; that command uses `this-command-keys' to find what prefix character was used, then uses `describe-bindings' to describe it. The following two functions are found in the library `helper'. They are for modes that want to provide help without relinquishing control, such as the "electric" modes. You must load that library with `(require 'helper)' in order to use them. Their names begin with `Helper' to distinguish them from the ordinary help functions. - Command: Helper-describe-bindings This command pops up a window displaying a help buffer containing a listing of all of the key bindings from both the local and global keymaps. It works by calling `describe-bindings'. - Command: Helper-help This command provides help for the current mode. It prompts the user in the minibuffer with the message `Help (Type ? for further options)', and then provides assistance in finding out what the key bindings are, and what the mode is intended for. It returns `nil'. This can be customized by changing the map `Helper-help-map'. File: elisp, Node: Files, Next: Backups and Auto-Saving, Prev: Documentation, Up: Top Files ***** In Emacs, you can find, create, view, save, and otherwise work with files and file directories. This chapter describes most of the file-related functions of Emacs Lisp, but a few others are described in *Note Buffers::, and those related to backups and auto-saving are described in *Note Backups and Auto-Saving::. * Menu: * Visiting Files:: Reading files into Emacs buffers for editing. * Saving Buffers:: Writing changed buffers back into files. * Reading from Files:: Reading files into buffers without visiting. * Writing to Files:: Writing new files from parts of buffers. * File Locks:: Locking and unlocking files, to prevent simultaneous editing by two people. * Information about Files:: Testing existence, accessibility, size of files. * Contents of Directories:: Getting a list of the files in a directory. * Create/Delete Dirs:: Creating and Deleting Directories. * Changing File Attributes:: Renaming files, changing protection, etc. * File Names:: Decomposing and expanding file names. * Magic File Names:: Defining "magic" special handling for certain file names. File: elisp, Node: Visiting Files, Next: Saving Buffers, Up: Files Visiting Files ============== Visiting a file means reading a file into a buffer. Once this is done, we say that the buffer is "visiting" that file, and call the file "the visited file" of the buffer. A file and a buffer are two different things. A file is information recorded permanently in the computer (unless you delete it). A buffer, on the other hand, is information inside of Emacs that will vanish at the end of the editing session (or when you kill the buffer). Usually, a buffer contains information that you have copied from a file; then we say the buffer is visiting that file. The copy in the buffer is what you modify with editing commands. Such changes to the buffer do not change the file; therefore, to make the changes permanent, you must "save" the buffer, which means copying the altered buffer contents back into the file. In spite of the distinction between files and buffers, people often refer to a file when they mean a buffer and vice-versa. Indeed, we say, "I am editing a file," rather than, "I am editing a buffer which I will soon save as a file of the same name." Humans do not usually need to make the distinction explicit. When dealing with a computer program, however, it is good to keep the distinction in mind. * Menu: * Visiting Functions:: The usual interface functions for visiting. * Subroutines of Visiting:: Lower-level subroutines that they use. File: elisp, Node: Visiting Functions, Next: Subroutines of Visiting, Up: Visiting Files Functions for Visiting Files ---------------------------- This section describes the functions normally used to visit files. For historical reasons, these functions have names starting with `find-' rather than `visit-'. *Note Buffer File Name::, for functions and variables that access the visited file name of a buffer or that find an existing buffer by its visited file name. - Command: find-file FILENAME This function reads the file FILENAME into a buffer and displays that buffer in the selected window so that the user can edit it. The body of the `find-file' function is very simple and looks like this: (switch-to-buffer (find-file-noselect filename)) (See `switch-to-buffer' in *Note Displaying Buffers::.) When `find-file' is called interactively, it prompts for FILENAME in the minibuffer. - Function: find-file-noselect FILENAME This function is the guts of all the file-visiting functions. It reads a file into a buffer and returns the buffer. You may then make the buffer current or display it in a window if you wish, but this function does not do so. If no buffer is currently visiting FILENAME, then one is created and the file is visited. If FILENAME does not exist, the buffer is left empty, and `find-file-noselect' displays the message `New file' in the echo area. If a buffer is already visiting FILENAME, then the `find-file-noselect' function uses that buffer rather than creating a new one. However, it does verify that the file has not changed since it was last visited or saved in that buffer. If the file has changed, then this function asks the user whether to reread the changed file. If the user says `yes', any changes previously made in the buffer are lost. The `find-file-noselect' function calls `after-find-file' after the file is read in (*note Subroutines of Visiting::.). The `after-find-file' function sets the buffer major mode, parses local variables, warns the user if there exists an auto-save file more recent than the file just visited, and finishes by running the functions in `find-file-hooks'. The `find-file-noselect' function returns the buffer that is visiting the file FILENAME. (find-file-noselect "/etc/fstab") => #<buffer fstab> - Command: find-alternate-file FILENAME This function reads the file FILENAME into a buffer and selects it, killing the buffer current at the time the command is run. It is useful if you have visited the wrong file by mistake, so that you can get rid of the buffer that you did not want to create, at the same time as you visit the file you intended. When this function is called interactively, it prompts for FILENAME. - Command: find-file-other-window FILENAME This function visits the file FILENAME and displays its buffer in a window other than the selected window. It may use another existing window or split a window; see *Note Displaying Buffers::. When this function is called interactively, it prompts for FILENAME. - Command: find-file-read-only FILENAME This function visits the file named FILENAME and selects its buffer, just like `find-file', but it marks the buffer as read-only. *Note Read Only Buffers::, for related functions and variables. When this function is called interactively, it prompts for FILENAME. - Command: view-file FILENAME This function views FILENAME in View mode, returning to the previous buffer when done. View mode is a mode that allows you to skim rapidly through the file but does not let you modify it. After loading the file, `view-file' runs the normal hook `view-hook' using `run-hooks'. *Note Hooks::. When this function is called interactively, it prompts for FILENAME. - Variable: find-file-hooks The value of this variable is a list of functions to be called after a file is visited. The file's local-variables specification (if any) will have been processed before the hooks are run. The buffer visiting the file is current when the hook functions are run. This variable could be a normal hook, but we think that renaming it would not be advisable. - Variable: find-file-not-found-hooks The value of this variable is a list of functions to be called when `find-file' or `find-file-noselect' is passed a nonexistent FILENAME. These functions are called as soon as the error is detected. `buffer-file-name' is already set up. The functions are called in the order given, until one of them returns non-`nil'. This is not a normal hook because the values of the functions are used and they may not all be run. File: elisp, Node: Subroutines of Visiting, Prev: Visiting Functions, Up: Visiting Files Subroutines of Visiting ----------------------- The `find-file-noselect' function uses the `create-file-buffer' and `after-find-file' functions as subroutines. Sometimes it is useful to call them directly. - Function: create-file-buffer FILENAME This function creates a suitably named buffer for visiting FILENAME, and returns it. The string FILENAME (sans directory) is used unchanged if that name is free; otherwise, a string such as `<2>' is appended to get an unused name. See also *Note Creating Buffers::. *Please note:* `create-file-buffer' does *not* associate the new buffer with a file and does not make it the current buffer. (create-file-buffer "foo") => #<buffer foo> (create-file-buffer "foo") => #<buffer foo<2>> (create-file-buffer "foo") => #<buffer foo<3>> This function is used by `find-file-noselect'. It uses `generate-new-buffer' (*note Creating Buffers::.). - Function: after-find-file &optional ERROR WARN This function is called by `find-file-noselect' and by the default revert function (*note Reverting::.). It sets the buffer major mode, and parses local variables (*note Auto Major Mode::.). If there was an error in opening the file, the calling function should pass ERROR a non-`nil' value. In that case, `after-find-file' issues a warning: `(New File)'. Note that, for serious errors, you would not even call `after-find-file'. Only "file not found" errors get here with a non-`nil' ERROR. If WARN is non-`nil', then this function issues a warning if an auto-save file exists and is more recent than the visited file. The last thing `after-find-file' does is call all the functions in `find-file-hooks'. File: elisp, Node: Saving Buffers, Next: Reading from Files, Prev: Visiting Files, Up: Files Saving Buffers ============== When you edit a file in Emacs, you are actually working on a buffer that is visiting that file--that is, the contents of the file are copied into the buffer and the copy is what you edit. Changes to the buffer do not change the file until you "save" the buffer, which means copying the contents of the buffer into the file. - Command: save-buffer &optional BACKUP-OPTION This function saves the contents of the current buffer in its visited file if the buffer has been modified since it was last visited or saved. Otherwise it does nothing. `save-buffer' is responsible for making backup files. Normally, BACKUP-OPTION is `nil', and `save-buffer' makes a backup file only if this is the first save or if the buffer was previously modified. Other values for BACKUP-OPTION request the making of backup files in other circumstances: * With an argument of 4 or 64, reflecting 1 or 3 `C-u''s, the `save-buffer' function marks this version of the file to be backed up when the buffer is next saved. * With an argument of 16 or 64, reflecting 2 or 3 `C-u''s, the `save-buffer' function unconditionally backs up the previous version of the file before saving it. - Command: save-some-buffers &optional SAVE-SILENTLY-P EXITING This command saves some modified file-visiting buffers. Normally it asks the user about each buffer. But if SAVE-SILENTLY-P is non-`nil', it saves all the file-visiting buffers without querying the user. The optional EXITING argument, if non-`nil', requests this function to offer also to save certain other buffers that are not visiting files. These are buffers that have a non-`nil' local value of `buffer-offer-save'. (A user who says yes to saving one of these is asked to specify a file name to use.) The `save-buffers-kill-emacs' function passes a non-`nil' value for this argument. - Variable: buffer-offer-save When this variable is non-`nil' in a buffer, Emacs offers to save the buffer on exit even if the buffer is not visiting a file. The variable is automatically local in all buffers. Normally, Mail mode (used for editing outgoing mail) sets this to `t'. - Command: write-file FILENAME This function writes the current buffer into file FILENAME, makes the buffer visit that file, and marks it not modified. The buffer is renamed to correspond to FILENAME unless that name is already in use. - Variable: write-file-hooks The value of this variable is a list of functions to be called before writing out a buffer to its visited file. If one of them returns non-`nil', the file is considered already written and the rest of the functions are not called, nor is the usual code for writing the file executed. If a function in `write-file-hooks' returns non-`nil', it is responsible for making a backup file (if that is appropriate). To do so, execute the following code: (or buffer-backed-up (backup-buffer)) You might wish to save the file modes value returned by `backup-buffer' and use that to set the mode bits of the file that you write. This is what `basic-save-buffer' does when it writes a file in the usual way. Here is an example showing how to add an element to `write-file-hooks' but avoid adding it twice: (or (memq 'my-write-file-hook write-file-hooks) (setq write-file-hooks (cons 'my-write-file-hook write-file-hooks))) - Variable: local-write-file-hooks This works just like `write-file-hooks', but it is intended to be made local to particular buffers. It's not a good idea to make `write-file-hooks' local to a buffer--use this variable instead. The variable is marked as a permanent local, so that changing the major mode does not alter a buffer-local value. This is convenient for packages that read "file" contents in special ways, and set up hooks to save the data in a corresponding way. - Variable: write-contents-hooks This works just like `write-file-hooks', but it is intended to be used for hooks that pertain to the contents of the file, as opposed to hooks that pertain to where the file came from. - Variable: after-save-hook This normal hook runs after a buffer has been saved in its visited file. - Variable: file-precious-flag If this variable is non-`nil', then `save-buffer' protects against I/O errors while saving by writing the new file to a temporary name instead of the name it is supposed to have, and then renaming it to the intended name after it is clear there are no errors. This procedure prevents problems such as a lack of disk space from resulting in an invalid file. (This feature worked differently in older Emacs versions.) Some modes set this non-`nil' locally in particular buffers. - User Option: require-final-newline This variable determines whether files may be written out that do *not* end with a newline. If the value of the variable is `t', then Emacs silently puts a newline at the end of the file whenever the buffer being saved does not already end in one. If the value of the variable is non-`nil', but not `t', then Emacs asks the user whether to add a newline each time the case arises. If the value of the variable is `nil', then Emacs doesn't add newlines at all. `nil' is the default value, but a few major modes set it to `t' in particular buffers. File: elisp, Node: Reading from Files, Next: Writing to Files, Prev: Saving Buffers, Up: Files Reading from Files ================== You can copy a file from the disk and insert it into a buffer using the `insert-file-contents' function. Don't use the user-level command `insert-file' in a Lisp program, as that sets the mark. - Function: insert-file-contents FILENAME &optional VISIT BEG END This function inserts the contents of file FILENAME into the current buffer after point. It returns a list of the absolute file name and the length of the data inserted. An error is signaled if FILENAME is not the name of a file that can be read. If VISIT is non-`nil', it also marks the buffer as unmodified and sets up various fields in the buffer so that it is visiting the file FILENAME: these include the buffer's visited file name and its last save file modtime. This feature is used by `find-file-noselect' and you should probably not use it yourself. If BEG and END are non-`nil', they should be integers specifying the portion of the file to insert. In this case, VISIT must be `nil'. For example, (insert-file-contents filename nil 0 500) inserts the first 500 characters of a file. If you want to pass a file name to another process so that another program can read the file, see the function `file-local-copy' in *Note Magic File Names::. File: elisp, Node: Writing to Files, Next: File Locks, Prev: Reading from Files, Up: Files Writing to Files ================ You can write the contents of a buffer, or part of a buffer, directly to a file on disk using the `append-to-file' and `write-region' functions. Don't use these functions to write to files that are being visited; that could cause confusion in the mechanisms for visiting. - Command: append-to-file START END FILENAME This function appends the contents of the region delimited by START and END in the current buffer to the end of file FILENAME. If that file does not exist, it is created. This function returns `nil'. An error is signaled if FILENAME specifies a nonwritable file, or a nonexistent file in a directory where files cannot be created. - Command: write-region START END FILENAME &optional APPEND VISIT This function writes the region (of the current buffer) delimited by START and END into the file specified by FILENAME. If START is a string, then `write-region' writes or appends that string, rather than text from the buffer. If APPEND is non-`nil', then the region is appended to the existing file contents (if any). If VISIT is `t', then Emacs establishes an association between the buffer and the file: the buffer is then visiting that file. It also sets the last file modification time for the current buffer to FILENAME's modtime, and marks the buffer as not modified. This feature is used by `write-file' and you should probably not use it yourself. If VISIT is a string, it specifies the file name to visit. This way, you can write the data to one file (FILENAME) while recording the buffer as visiting another file (VISIT). The argument VISIT is used in the echo area message and also for file locking; VISIT is stored in `buffer-file-name'. This feature is used to implement `file-precious-flag'; don't use it yourself unless you really know what you're doing. Normally, `write-region' displays a message `Wrote file FILENAME' in the echo area. If VISIT is neither `t' nor `nil' nor a string, then this message is inhibited. This feature is useful for programs that use files for internal purposes, files which the user does not need to know about. File: elisp, Node: File Locks, Next: Information about Files, Prev: Writing to Files, Up: Files File Locks ========== When two users edit the same file at the same time, they are likely to interfere with each other. Emacs tries to prevent this situation from arising by recording a "file lock" when a file is being modified. Emacs can then detect the first attempt to modify a buffer visiting a file that is locked by another Emacs job, and ask the user what to do. File locks do not work properly when multiple machines can share file systems, such as with NFS. Perhaps a better file locking system will be implemented in the future. When file locks do not work, it is possible for two users to make changes simultaneously, but Emacs can still warn the user who saves second. Also, the detection of modification of a buffer visiting a file changed on disk catches some cases of simultaneous editing; see *Note Modification Time::. - Function: file-locked-p FILENAME This function returns `nil' if the file FILENAME is not locked by this Emacs process. It returns `t' if it is locked by this Emacs, and it returns the name of the user who has locked it if it is locked by someone else. (file-locked-p "foo") => nil - Function: lock-buffer &optional FILENAME This function locks the file FILENAME, if the current buffer is modified. The argument FILENAME defaults to the current buffer's visited file. Nothing is done if the current buffer is not visiting a file, or is not modified. - Function: unlock-buffer This function unlocks the file being visited in the current buffer, if the buffer is modified. If the buffer is not modified, then the file should not be locked, so this function does nothing. It also does nothing if the current buffer is not visiting a file. - Function: ask-user-about-lock FILE OTHER-USER This function is called when the user tries to modify FILE, but it is locked by another user name OTHER-USER. The value it returns tells Emacs what to do next: * A value of `t' tells Emacs to grab the lock on the file. Then this user may edit the file and OTHER-USER loses the lock. * A value of `nil' tells Emacs to ignore the lock and let this user edit the file anyway. * This function may instead signal a `file-locked' error, in which case the change to the buffer which the user was about to make does not take place. The error message for this error looks like this: error--> File is locked: FILE OTHER-USER where `file' is the name of the file and OTHER-USER is the name of the user who has locked the file. The default definition of this function asks the user to choose what to do. If you wish, you can replace the `ask-user-about-lock' function with your own version that decides in another way. The code for its usual definition is in `userlock.el'. File: elisp, Node: Information about Files, Next: Contents of Directories, Prev: File Locks, Up: Files Information about Files ======================= The functions described in this section are similar in as much as they all operate on strings which are interpreted as file names. All have names that begin with the word `file'. These functions all return information about actual files or directories, so their arguments must all exist as actual files or directories unless otherwise noted. Most of the file-oriented functions take a single argument, FILENAME, which must be a string. The file name is expanded using `expand-file-name', so `~' is handled correctly, as are relative file names (including `../'). Environment variable substitutions, such as `$HOME', are not recognized by these functions. *Note File Name Expansion::. * Menu: * Testing Accessibility:: Is a given file readable? Writable? * Kinds of Files:: Is it a directory? A symbolic link? * Truenames:: Eliminating symbolic links from a file name. * File Attributes:: How large is it? Any other names? Etc. File: elisp, Node: Testing Accessibility, Next: Kinds of Files, Up: Information about Files Testing Accessibility --------------------- These functions test for permission to access a file in specific ways. - Function: file-exists-p FILENAME This function returns `t' if a file named FILENAME appears to exist. This does not mean you can necessarily read the file, only that you can find out its attributes. (On Unix, this is true if the file exists and you have execute permission on the containing directories, regardless of the protection of the file itself.) If the file does not exist, or if fascist access control policies prevent you from finding the attributes of the file, this function returns `nil'. - Function: file-readable-p FILENAME This function returns `t' if a file named FILENAME exists and you can read it. It returns `nil' otherwise. (file-readable-p "files.texi") => t (file-exists-p "/usr/spool/mqueue") => t (file-readable-p "/usr/spool/mqueue") => nil - Function: file-executable-p FILENAME This function returns `t' if a file named FILENAME exists and you can execute it. It returns `nil' otherwise. If the file is a directory, execute permission means you can access files inside the directory. - Function: file-writable-p FILENAME This function returns `t' if FILENAME can be written or created by you. It is writable if the file exists and you can write it. It is creatable if the file does not exist, but the specified directory does exist and you can write in that directory. `file-writable-p' returns `nil' otherwise. In the third example below, `foo' is not writable because the parent directory does not exist, even though the user could create it. (file-writable-p "~rms/foo") => t (file-writable-p "/foo") => nil (file-writable-p "~rms/no-such-dir/foo") => nil - Function: file-accessible-directory-p DIRNAME This function returns `t' if you have permission to open existing files in directory DIRNAME; otherwise (and if there is no such directory), it returns `nil'. The value of DIRNAME may be either a directory name or the file name of a directory. Example: after the following, (file-accessible-directory-p "/foo") => nil we can deduce that any attempt to read a file in `/foo/' will give an error. - Function: file-newer-than-file-p FILENAME1 FILENAME2 This functions returns `t' if the file FILENAME1 is newer than file FILENAME2. If FILENAME1 does not exist, it returns `nil'. If FILENAME2 does not exist, it returns `t'. You can use `file-attributes' to get a file's last modification time as a list of two numbers. *Note File Attributes::. In the following example, assume that the file `aug-19' was written on the 19th, and `aug-20' was written on the 20th. The file `no-file' doesn't exist at all. (file-newer-than-file-p "aug-19" "aug-20") => nil (file-newer-than-file-p "aug-20" "aug-19") => t (file-newer-than-file-p "aug-19" "no-file") => t (file-newer-than-file-p "no-file" "aug-19") => nil File: elisp, Node: Kinds of Files, Next: Truenames, Prev: Testing Accessibility, Up: Information about Files Distinguishing Kinds of Files ----------------------------- This section describes how to distinguish directories and symbolic links from ordinary files. - Function: file-symlink-p FILENAME If FILENAME is a symbolic link, the `file-symlink-p' function returns the file name to which it is linked. This may be the name of a text file, a directory, or even another symbolic link, or of no file at all. If FILENAME is not a symbolic link (or there is no such file), `file-symlink-p' returns `nil'. (file-symlink-p "foo") => nil (file-symlink-p "sym-link") => "foo" (file-symlink-p "sym-link2") => "sym-link" (file-symlink-p "/bin") => "/pub/bin" - Function: file-directory-p FILENAME This function returns `t' if FILENAME is the name of an existing directory, `nil' otherwise. (file-directory-p "~rms") => t (file-directory-p "~rms/lewis/files.texi") => nil (file-directory-p "~rms/lewis/no-such-file") => nil (file-directory-p "$HOME") => nil (file-directory-p (substitute-in-file-name "$HOME")) => t File: elisp, Node: Truenames, Next: File Attributes, Prev: Kinds of Files, Up: Information about Files Truenames --------- The "truename" of a file is the name that you get by following symbolic links until none remain, then expanding to get rid of `.' and `..' as components. Strictly speaking, a file need not have a unique truename; the number of distinct truenames a file has is equal to the number of hard links to the file. However, truenames are useful because they eliminate symbolic links as a cause of name variation. - Function: file-truename FILENAME The function `file-truename' returns the true name of the file FILENAME. This is the name that you get by following symbolic links until none remain. The argument must be an absolute file name. *Note Buffer File Name::, for related information.